/*
 * Package externalModules
 * File ISipEventNotificationProvider.java
 * Created on Jul 27, 2005
 *
 */
package il.ac.biu.cs.grossmm.api.simple;

import il.ac.biu.cs.grossmm.api.flow.Status;
import il.ac.biu.cs.grossmm.api.presence.ResourceType;

/**
 * This interface represents an entity implementing SIP specific event
 * notification as described in RFC 3261. This entity normally does not handle
 * any subscriptions directly, rather passes them to corresponding instances of
 * <code>ISipEventPackage</code> attached to it. Instances of
 * <code>ISipEventPackage</code> represent SIP event packages and SIP event
 * template-packages, such as presence.
 * 
 * <br>
 * Operation:
 * <ol>
 * <li> Call addPackage method to add one or more <code>SipEventPackage</code> instances
 * <li> When a new SUBSCRIBE message is received it is forwarded to the attached
 * SipEventPackage instance whose <code>getPackageName</code> method returns
 * value matches the event-type specified in the message. This forwarding
 * is performed by calling <code>SipEventPackage.createSubscription</code>.
 * <li> SipEventPackage creates an <code>SipSubscription</code> instance
 * which will handle the ongoing subscription refreshes, this instance
 * should be registered by calling <code>addSubscription</code> method of
 * this interface.
 * </ol>
 * 
 */
public interface SipNotificationProvider {
    
    /**
     * Returns the instance of ISharedProvider to be used to 
     * generate responces.
     * @return the instance of ISharedProvider to be used to 
     * generate responces
     */
    SipSharedProvider getSharedProvider();
    
    /**
     * Attaches SIP event package implementation
     * 
     * @param eventPackage
     *            class which implements a specific event package to attach
     */
    void addPackage(SipEventPackage eventPackage);

    /**
     * Detaches SIP event package implementation
     * 
     * @param eventPackage
     *            class which implements a specific event package to dettach
     */
    void removePackage(SipEventPackage eventPackage);

    /**
     * Called when status of an internal subscription changes
     * 
     * @param internal internal subscription
     * @param status the new status
     */
    void setState(InternalSubscription internal, Status status);
    
    /**
     * Given a SIP event-type (for a simple package or a template package)
     * returns corresponding resource type.
     *  
     * @param eventType
     * @return
     */
    ResourceType getResourceType(String eventType);

	void initialized(SipSubscription sipSub);
}
